﻿<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
  
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Images </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Images ">
    <meta name="generator" content="docfx 2.59.2.0">
    
    <link rel="shortcut icon" href="../../favicon.ico">
    <link rel="stylesheet" href="../../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../../styles/docfx.css">
    <link rel="stylesheet" href="../../styles/main.css">
    <link rel="stylesheet" href="../../styles/socialbar.css">
    <link rel="stylesheet" href="../../styles/header.css">
    <link rel="stylesheet" href="../../styles/version.css">
    <link href="https://fonts.googleapis.com/css?family=Roboto:400,100,300,500,700,100italic,300italic,400italic" rel="stylesheet" type="text/css">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
    <meta property="docfx:navrel" content="../../toc.html">
    <meta property="docfx:tocrel" content="../toc.html">
    <meta property="docfx:uid" content="doc-restapi-Images">
    
    <meta property="docfx:rel" content="../../">
    
    <script type="text/javascript" src="../../nav.js"></script>
    <script type="text/javascript" src="../toc.js"></script>
  
  </head>  <body data-spy="scroll" data-target="#affix" data-offset="120">
    <div id="wrapper">
      <header>
        
        <div class="mb-socials-heading" style="height: 40px;">
        	<div class="mb-socials-heading-inner container">
        		<div class="mb-socials-heading-right">
        			<div class="mb-socials-list">
                          
        				<div class="mb-socials-item facebook">
        					<a class="mb-socials-item-link" target="_blank" href="https://facebook.com/embyapp"></a>
        					<div class="mb-socials-item-popup">
        						<span>Facebook</span>
        					</div>
        				</div><div class="mb-socials-item twitter">
        					<a class="mb-socials-item-link" target="_blank" href="https://twitter.com/embyapp"></a>
        					<div class="mb-socials-item-popup">
        						<span>Twitter</span>
        					</div>
        				</div>
        				<div class="mb-socials-item pinterest">
        					<a class="mb-socials-item-link" target="_blank" href="https://www.pinterest.com/emby0240/emby-news/"></a>
        					<div class="mb-socials-item-popup">
        						<span>Pinterest</span>
        					</div>
        				</div>
        				<div class="mb-socials-item tumblr">
        					<a class="mb-socials-item-link" target="_blank" href="https://embyapp.tumblr.com/"></a>
        					<div class="mb-socials-item-popup">
        						<span>Tumblr</span>
        					</div>
        				</div>
        				<div class="mb-socials-item github">
        					<a class="mb-socials-item-link" target="_blank" href="https://github.com/MediaBrowser"></a>
        					<div class="mb-socials-item-popup">
        						<span>GitHub</span>
        					</div>
        				</div><div class="mb-socials-item rss">
        					<a class="mb-socials-item-link" target="_blank" href="https://emby.media/blog.xml"></a>
        					<div class="mb-socials-item-popup">
        						<span>RSS</span>
        					</div>
        				</div>
                          
        			</div>
        		</div>
        	</div>
        </div>
        <div class="container">
        	<nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
        		  
        		  <a class="navbar-brand" href="../../index.html">
        		    <img id="logo" class="svg" src="../../images/emby_dev_logo.png" alt="">
        		  </a>
        		  <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
        			<span class="sr-only">Toggle navigation</span>
        			<span class="icon-bar"></span>
        			<span class="icon-bar"></span>
        			<span class="icon-bar"></span>
        		  </button>
        		<div class="collapse navbar-collapse" id="navbar">
        			
        			<ul class="nav level1 navbar-nav">
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../index.html" title="DEV Home">DEV Home</a>
        			      </li>
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../doc/index.html" title="Documentation">Documentation</a>
        			      </li>
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../reference/index.html" title="Reference">Reference</a>
        			      </li>
        			      <li class="nav-item">
        			          <a class="nav-link" href="../../download/index.html" title="Download">Download</a>
        			      </li>
        			</ul>		</div>
        	</nav>
        </div>
        <div class="nav-overlay d-none"></div>        
        <div class="subnav navbar navbar-default">
          <div class="container">
            <div class="hide-when-search" id="breadcrumb">
        	  <ul class="breadcrumb">
        		<li></li>
        	  </ul>
        	</div>
        
        	<div class="breadcrumpsearch">
        	  <form class="navbar-form navbar-right" role="search" id="search">
        		<div class="form-group">
        		  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
        		</div>
        	  </form>
        	</div>
          </div>
        </div>
      </header>
      <div class="container body-content">
        
        <div id="search-results">
          <div class="search-list">Search Results for <span></span></div>
          <div class="sr-items">
            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
          </div>
          <ul id="pagination" data-first="First" data-prev="Previous" data-next="Next" data-last="Last"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="doc-restapi-Images">
<h1 id="images">Images</h1>

<p>Image values are added to response objects to indicate what images an item has. For example, on the User object, there is a property called PrimaryImageTag. If this has a value, it means the user has a primary image.</p>
<p>An image should only downloaded if the object indicates the presence of an image. For example, you will receive a 404 error if you attempt to download a logo image for an item that doesn't have one.</p>
<h2 id="downloading-images">Downloading images</h2>
<p>The url required to download images will vary depending on what kind of item you're downloading for. For example, for users, the url's are</p>
<ul>
<li><a class="xref" href="../../reference/RestAPI/ImageService/getUsersByIdImagesByType.html">/Users/{Id}/Images/{Type}</a> and</li>
<li><a class="xref" href="../../reference/RestAPI/ImageService/getUsersByIdImagesByTypeByIndex.html">/Users/{Id}/Images/{Type}/{Index}</a></li>
</ul>
<p>For media items, it's</p>
<ul>
<li><a class="xref" href="../../reference/RestAPI/ImageService/getItemsByIdImagesByType.html">/Items/{Id}/Images/{Type}</a> as well as</li>
<li><a class="xref" href="../../reference/RestAPI/ImageService/getItemsByIdImagesByTypeByIndex.html">/Items/{Id}/Images/{Type}/{Index}</a></li>
</ul>
<p>Below are the <strong>required</strong> image parameters:</p>
<h3 id="type">Type</h3>
<p>This is the type of image. These are the available types:</p>
<ul>
<li>Primary</li>
<li>Art</li>
<li>Backdrop</li>
<li>Banner</li>
<li>Logo</li>
<li>Thumb</li>
<li>Disc</li>
<li>Box</li>
<li>Screenshot</li>
<li>Menu</li>
<li>Chapter</li>
</ul>
<h3 id="index">Index</h3>
<p>If downloading a backdrop, screenshot, or chapter image, you will need to specify the index because the item could contain more than one. The item object will contain count properties indicating how many of each are available.</p>
<p>Aside from item Id, the image type is the only other required parameter. Index is required depending on the type of image requested.</p>
<p>Below are the available <strong>optional</strong> parameters:</p>
<h3 id="width-height-maxwidth-maxheight">Width, Height, MaxWidth, MaxHeight</h3>
<p>Users will often download high resolution images. Steps should be taken to ensure that you are not retrieving these at full size. You can use any combination of these values. For example, if you specify a width of 80, you'll get the image at a fixed width of 80 and allow the height to vary, preserving aspect ratio. Specify both width and height to force an exact size. Specify MaxWidth and/or MaxHeight to create a size limit.</p>
<p>Most image types generally have a predictable aspect ratio. Primary is the one exception where it can vary. In order to combat this, we include a PrimaryImageAspectRatio property on items. A typical scenario might be to create an average AR for all the items in the list, and then force all images to that value.</p>
<h3 id="tag">Tag</h3>
<p>The image tag on the item object also doubles as a caching value. If you add this parameter back onto your image url, you will receive strong http caching headers. This allows you to cache the image forever, unconditionally, based on the url. If the image changes, the tag will also change, thus creating a whole new url.</p>
<p>Note: It is recommended to cache based on the url <strong>after the hostname and port</strong>. This will allow the same cache to be utilized whether connected internally (lan/wifi) or externally (mobile).</p>
<p>This is an optional parameter. You do not have to specify the tag, but without it you will only receive conditional http response caching.</p>
<h2 id="image-inheritance">Image Inheritance</h2>
<p>We allow some images to be inherited from parent items, namely backdrops and logos.</p>
<p>If an item does not have backdrops or logos, there are properties that will indicate what parent images are available for inheritance:</p>
<ul>
<li>ParentLogoItemId - The id of an ancestor item with a logo</li>
<li>ParentLogoImageTag - The cache tag of the ancestor logo image</li>
<li>ParentArtItemId - The id of an ancestor item with an art image</li>
<li>ParentArtImageTag - The cache tag of the ancestor art image</li>
<li>ParentBackdropItemId - The id of an ancestor item with backdrop images</li>
<li>ParentBackdropImageTags - The cache tags of the ancestor backdrop images</li>
<li>ParentThumbItemId - The id of an ancestor item with a thumb image</li>
<li>ParentThumbImageTag - The cache tags of the ancestor thumb image</li>
</ul>
<h2 id="image-format">Image Format</h2>
<p>By default, images are returned in the original format, which generally will be either png or jpg. If the user has image enhancer plugins installed such as Cover Art, the default output format will be forced to png.</p>
<p>If a specific output format is needed, this can be controlled using the <strong>format param</strong>. Available values are:</p>
<ul>
<li>bmp</li>
<li>gif</li>
<li>jpp</li>
<li>png</li>
</ul>
<p>If forcing to jpg it's possible that some transparency will be lost. It's recommended to apply a background color of your choosing using the <strong>backgroundColor param</strong>, which accepts html color values, such as #000000 or red.</p>
<h2 id="adding-a-played-indicator">Adding a Played Indicator</h2>
<p>A played indicator overlay can be added onto the image using <strong>AddPlayedIndicator=true</strong></p>
<h2 id="adding-a-percent-played-indicator">Adding a Percent Played Indicator</h2>
<p>A percent played overlay can be added onto the image using <strong>PercentPlayed=47</strong></p>
</article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                </ul>
              </div>
              <div class="sdkversion Release">
                  SDK <span class="sdkVersionSpan"></span>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
                <h5>On this Page</h5>
                <div></div>
              </nav>
            </div>
          </div>
        </div>
      </div>
      
      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to Top</a>
            </span>
            Copyright 2022 © EMBY LLC.  Please see our <a class="lnk" href="https://emby.media/terms.html">terms of use</a> and <a class="lnk" href="https://emby.media/privacy.html">privacy policy</a>.
            
          </div>
        </div>
      </footer>
    </div>
    
    <script type="text/javascript" src="../../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../../searchIndex.js"></script>
    <script type="text/javascript" src="../../styles/lunr.min.js"></script>
    <script type="text/javascript" src="../../styles/docfx.js"></script>
    <script type="text/javascript" src="../../styles/main.js"></script>
  </body>
</html>
